package org.vaadin.vaadinjit.data;

import java.util.List;


/**
 * This is the interface for the data model used by the chart visualizations 
 * in JIT.
 * 
 * @author jonkka
 *
 */
public interface JitChartData extends JitData {

	
	/**
	 * <p>
	 * Add a new category with the given label (name). The label has to be
	 * unique within the data model. <br />
	 * </p>
	 * 
	 * <p>
	 * Together with data points the categories form a X-Y coordnitate system,
	 * where each point contains integer data for the visualization
	 * </p>
	 * 
	 * @param label the label name
	 */
	public void addCategory(String label);
	
	
	/**
	 * <p>
	 * Add a new data point. The data point name has to be unique within the
	 * data model.
	 * </p>
	 * 
	 * <p>
	 * Together with categories the data points form a X-Y coordnitate system,
	 * where each point contains integer data for the visualization
	 * </p>
	 * 
	 * @param dataPoint
	 */
	public void addDataPoint(String dataPoint);
	
	
	/**
	 * Set the value for the given point. The point is given by the category
	 * and data point.
	 * 
	 * @param label the category
	 * @param dataPoint the data point
	 * @param value the value
	 */
	public void setValue(String label, String dataPoint, int value);
	
	/**
	 * Set the value for the given point. The point is given by the category
	 * and data point.
	 * 
	 * @param label the category
	 * @param dataPoint the data point
	 * @param value the value
	 */
	public void setValue(String label, String dataPoint, double value);
	
	
	/**
	 * Get the value in the given point.
	 * 
	 * @param label the category
	 * @param dataPoint the data point
	 * @return the value in the point
	 */
	public double getValue(String label, String dataPoint);
	
	
	/**
	 * Add a new change listener
	 * 
	 * @param listener the listener
	 */
	public void addChangeListener(ChangeListener listener);
	
	
	/**
	 * Get a list of the categories
	 * 
	 * @return a list of the categories
	 */
	public List<String> getCategories();
	
	
	/**
	 * Get the data points
	 * 
	 * @return a list of all data points
	 */
	public List<String> getDataPoints();
	
	
	/**
	 * Can be used to manually notify listeners that the data has been changed.
	 */
	public void notifyChanged();
	
	/**
	 * Interface for listening to data changes.
	 * 
	 * @author jonkka
	 *
	 */
	public interface ChangeListener {

		
		/**
		 * Fired when a value is set in the data model.
		 * 
		 * @param label the label
		 * @param dataPoint the data point
		 * @param value the set value
		 */
		public void valueSet(String label, String dataPoint, double value);

		
		/**
		 * Fired when a data point is added.
		 * 
		 * @param dataPoint the name of the data point
		 */
		public void dataPointAdded(String dataPoint);

		
		/**
		 * Fired when a category is added
		 * 
		 * @param label the name of the category
		 */
		public void categoryAdded(String label);
		
		
		/**
		 * Notifies listeners that values in the structure has changed
		 */
		public void valuesChanged();
		
	}
	
}
